<!--
layout: default
title: 框架说明
slug: start
lead: "了解设计规范."
base_url: "./" -->
<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="description" content="ZUI，一个简单灵活的前端框架。">
    <meta name="author" content="Zentao">

    <title>ZUI - 开源HTML5跨屏框架</title>

    <link href="css/zui.min.css" rel="stylesheet">
    <link href="css/doc.css" rel="stylesheet">

    <!--[if lt IE 9]>
    <script src="../assets/html5shiv.js"></script>
    <script src="../assets/respond.js"></script>
    <![endif]-->
  </head>
  <body class="doc-start">
    <header data-tab="start">
    </header>
    <div id="main">
      <div class="page-header">
        <h1>开始</h1>
      </div>

      <section id="intro">
        <div class="page-header">
          <h2>说明</h2>
        </div>

        <h3>与Bootstrap的关系</h3>
        <p>ZUI继承了Bootstrap 3中的大部分基础内容，但出于与Bootstrap不同的目的大部分内容都进行了定制和修改。这些变化包括：</p>
        <ul>
          <li>移除了部分插件的限制，增加了一些适用特性，例如Popover弹出的内容可以指定已有的标签内容,Modal对话框可以自动使用iframe弹出整个页面内容等；</li>
          <li>增加了实用的视图组件，包括卡片、评论、列表、文章、仪表盘、看板等；</li>
          <li>新增了几个Javascript组件，包括拖放、排序、灯箱预览，本地存储，图片裁剪等；</li>
          <li>集成了一些实用的第三方组件，包括cookie、hotkey、chosen、Kindeditor、ChartJs、DatetimePicker等，并且这些组件样式经过重写，风格更为统一；</li>
          <li>增加了配色表和新的主题模板，最少只需更改一个配置项更换颜色主题；</li>
          <li>修改了默认字体配置，包含所使用的字体集和字体大小；</li>
          <li>替换了默认的字体图标，在FontAwesome图标集的基础上去掉了一些图标同时增加了一些新的图标，写法上比FontAwesome更简单；</li>
          <li>大部分组件的默认样式都不需要额外的指定包含&#39;default&#39;的Class，例如class=&#39;btn btn-default&#39;，&#39;btn-default&#39;在ZUI中不需要；</li>
          <li>增加了一些辅助类，例如文本背景及高亮等；</li>
          <li>增加了一些可选样式，例如滚动条等。</li>
        </ul>

        <h3>选择使用ZUI</h3>
        <p>Bootstrap是非常优秀的前端框架，但在构建大型应用的开发时通常远远不够。如果Bootstrap能够完全满足你的项目，建议使用Bootstrap，如果你需要的更多，则建议使用ZUI。使用ZUI的显著理由如下：</p>
        <ul>
          <li>大部分书写方式继承Bootstrap，从Bootstrap方便迁移到ZUI，学习成本低，而且写法上更精简；</li>
          <li>需要的实用功能都能在ZUI中提供，即使是第三方组件也提供统一的样式和主题支持；</li>
          <li>即使ZUI包含的内容更丰富，也会控制核心内容打包后体积大小，一般css不超过150k（目前130k，精简版95k），js不超过100k（目前79k，精简版33k），精简版包含绝大部分功能，但体积更小。非核心内容按需加载，推荐自定义编译；</li>
          <li>ZUI从实际项目中诞生（包括禅道、蝉知和然之），实践证明其有效性，一切为了快速构建你的应用；</li>
          <li>一些令人激动的新内容正在开发中...</li>
        </ul>
      </section>

      <section id="about">
        <div class="page-header">
          <h2>约定</h2>
        </div>
        <h3>UI元素类型及定义</h3>
        <p>ZUI中包含各种各样的界面元素（或控件），例如按钮、列表、表格等，甚至一些特定场景用到的一组元素也会在ZUI中精心设计，例如评论列表。为了更好的展示我们的设计理念，把这些元素归为如下四类：</p>
        <ul>
          <li><strong>基本控件</strong>：用来构建网页应用的基本界面单元，例如按钮、文本标签、输入框等。</li>
          <li><strong>组件</strong>：通过一个以上的基本控件组合而成的较复杂的界面单元。例如表单、菜单、表格等。</li>
          <li><strong>Javascript 组件</strong>：这些组件要正常使用会使用到Javascript。某些Javascript组件需要手动调用来启用。</li>
          <li><strong>视图</strong>：视图是将基本控件和组件组合使用来展现网站上的通用内容，例如评论视图及文章预览列表视图。</li>
        </ul>
        <p>ZUI中的大多数界面元素都有不同的子类型、状态及参数。关于类型、状态及参数的定义如下：</p>
        <ul>
          <li><strong>类型</strong>：同一种界面单元的不同类型，例如按钮有主要按钮、次要按钮及危险按钮等，导航菜单类型有普通导航及顶部固定导航等。任何时候都应该只为同一个界面元素指定一种类型，默认类型无需指定。</li>
          <li><strong>状态</strong>：状态为同一种界面单元允许在不同的状态中切换，例如按钮有正常状态和不可用状态，下拉菜单有展开及收拢状态，菜单项目有选中和未选中状态等。在同一个界面元素中允许叠加多个状态。</li>
          <li><strong>参数</strong>：参数作为界面单元如何展现提供依据，例如表格是否隔行变色，是否启用鼠标悬停等。可以同时指定多个参数。</li>
        </ul>

        <h3>通用状态和参数</h3>
        <p>很多状态和参数在不同的控件或组件中具有一致的用法和相同的含义。在ZUI中，这些通用的状态和参数具有固定的名字（CSS 类名）。</p>
        <p>常用通用状态如下：</p>
        <table class="table table-bordered">
          <thead>
            <tr>
              <th style="width: 80px">名称</th>
              <th>说明</th>
              <th>常见使用对象</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>.active</code></td>
              <td>指示控件或者其子项目已经被激活。</td>
              <td>导航条目、下拉菜单条目、菜单列表、按钮组中可以激活的按钮等。</td>
            </tr>
            <tr>
              <td><code>.hover</code></td>
              <td>指示控件正处于鼠标悬停状态，在CSS中相对于<code>:hover</code>选择器。</td>
              <td>少部分需要Javascript处理的控件。</td>
            </tr>
            <tr>
              <td><code>.focus</code></td>
              <td>指示控件正处于鼠标悬停状态，在CSS中相对于<code>:focus</code>选择器。</td>
              <td>少部分需要Javascript处理的控件。</td>
            </tr>
            <tr>
              <td><code>.disabled</code></td>
              <td>指示控件处于不可用状态，通常与DOM属性<code>disabled="disabled"</code>一起使用。</td>
              <td>按钮、可以点击菜单项目、超链接、表单元素等。</td>
            </tr>
            <tr>
              <td><code>.in</code></td>
              <td>用于控制控件显示或消失的动画过程。在控件显示时指示控件已准备完成CSS动画并完全显示；在控件消失时如果移除该状态指示控件已准备执行控件消失动画；与状态<code>.collapse</code>一起使用时表示处于完全展开状态。</td>
              <td>标签页、下拉菜单等</td>
            </tr>
            <tr>
              <td><code>.open</code></td>
              <td>指示隐藏的内容已经完全展示。</td>
              <td>下拉菜单等。</td>
            </tr>
            <tr>
              <td><code>.collapse</code></td>
              <td>指示当前组件可以被折叠或展开。与状态<code>.in</code>一起出现时表示组件已被展开，没有此状态则反之。</td>
              <td>响应式导航、折叠菜单等。</td>
            </tr>
            <tr>
              <td><code>.collapsing</code></td>
              <td>指示当前组件正处于折叠或展开的动画过程中。</td>
              <td>响应式导航、折叠菜单等。</td>
            </tr>
          </tbody>
        </table>
        <p>常见的通用参数如下：</p>
        <table class="table table-bordered">
          <thead>
            <tr>
              <th style="width: 80px">名称</th>
              <th>说明</th>
              <th>常见使用对象</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><code>.bordered</code></td>
              <td>使得组件具备边框样式。</td>
              <td>表格等。</td>
            </tr>
            <tr>
              <td><code>.borderless</code></td>
              <td>移除控件的边框样式。</td>
              <td>表格等。</td>
            </tr>
            <tr>
              <td><code>.inverse</code></td>
              <td>指示组件使用与默认颜色样式相对的样式。</td>
              <td>导航等。</td>
            </tr>
            <tr>
              <td><code>.fixed</code></td>
              <td>指示当前组件位置被固定，不收页面交互影响。</td>
              <td></td>
            </tr>
            <tr>
              <td><code>.with-icon</code></td>
              <td>指示当前组件在显示内容时能够额外显示一个图标。</td>
              <td>消息框等。</td>
            </tr>
            <tr>
              <td><code>.with-padding</code></td>
              <td>指示当前组件内容显示区域包含更多的边距。</td>
              <td></td>
            </tr>
          </tbody>
        </table>

        <h3>界面元素的命名</h3>
        <h4>命名原则</h4>
        <ul>
          <li>所有控件、组件、视图、模块和行为的命名都应该使用最常见的名称，准确提现界面元素功能。例如菜单应该命名为menu，而不是navigation。</li>
          <li>类型、状态及参数的命名均为元素名加上类型（或状态及参数名）前缀，中间用间隔号分隔，例如固定位置的菜单为<code>.menu-fixed</code>。对于通用状态或参数可以省略前缀，例如一个菜单项目处于激活状态，则只需命名为<code>.active</code>，而不许命名为<code>.menu-active</code>。</li>
          <li>所有控件、组件、视图、模块和行为的命名均不加与当前元素功能无关的前缀和额外命名，例如一个导航菜单命名为<code>.nav</code>，而不增加额外命名为<code>.ui.nav</code>或者<code>.zui.nav</code>。</li>
        </ul>
      </section>

      <section id="files">
        <div class="page-header">
          <h2>文件目录结构</h2>
        </div>

        <h3>预编译的内容</h3>
        <p>下载预编译压缩包解压后将会得到以下目录结构：</p>
        <pre>
zui/
├── css/
│   ├── zui.css
│   ├── zui.min.css
│   ├── zui.lite.css
│   ├── zui.lite.min.css
│   ├── zui-theme.css
│   └── zui-theme.min.css
├── js/
│   ├── zui.js
│   ├── zui.min.js
│   ├── zui.lite.js
│   └── zui.lite.min.js
├── fonts/
│   ├── zenicon.eot
│   ├── zenicon.svg
│   ├── zenicon.ttf
│   └── zenicon.woff
└── lib
        </pre>
        <p>css目录下提供了三种编译类型：‘zui’、‘zui.lite’、‘zui-theme’，其中‘zui.lite’为精简版样式（关于精简版请参考本文档后续章节），‘zui-theme’为zui的主题样式。每种编译类型均提供了压缩版本，对应的文件名为‘*.min.css’。js目录下提供对应的js文件。字体图标放在‘fonts’文件夹下。lib目录下存放一些可以独立使用的组件。</p>

        <h3>源码目录结构</h3>
        <p>可以随时从Github上下载ZUI的源码。不仅仅包含所有开发源码文件，而且包含完整的文档和示例。如果你需要定制的编译版本更应该下载源码。以下简要说明源码目录结构。</p>
<pre>
zui/
├── src/                         ZUI的源码目录
│   ├── less/
│   ├── js/
│   ├── fonts/
│   └── apps/                    一些自定义的编译配置
├── dist/                        预编译输出目录
│   ├── css/
│   ├── js/
│   └── fonts/
├── docs/                        文档
│   └── example/                 文档中用到的例子
├── assets/                      一些依赖的或者配合使用的其他资源，包含jquery等
├── Gruntfile.js                 Grunt编译脚本
└── index.html                   文档首页
</pre>
      </section>

      <section id="edition">
        <div class="page-header">
          <h2>选择版本</h2>
        </div>
        <p>ZUI中提供了众多丰富的web组件，几乎为你准备构建现代Web应用所有基础内容。但大部分场景并不需要所有组件，所有并没有将所有内容打包为一个CSS文件和一个JS文件，在标准版中仅包含精心选择的组件，这些组件用于绝大部分场景。</p>
        <p>在构建轻量的应用时需要的内容更少。ZUI预编译版本中提供了一些简洁的版本。包含了ZUI中大部分常用内容，经过压缩后体积更小。你可以在dist目录下找到文件名包含'.lite'的文件记为简洁的版本。</p>
        <h3>标准版</h3>
        <p>在标准版中包含绝大部分常用组件。预编译的标准版包含以下文件：</p>
<pre>
zui/
└── dist/
    ├── css/                    CSS文件
    │   ├── zui.css
    │   ├── zui.min.css
    │   └── zui.map.css
    ├── js/                     Javascript文件
    │   ├── zui.js
    │   └── zui.min.js
    └── fonts/                  图标字体文件
        ├── zenicon.eot
        ├── zenicon.ttf
        ├── zenicon.woff
        └── zenicon.svg
</pre>
        <h3>简洁版</h3>
        <p>在简洁版中包含大部分常用组件。标准版中已包含简洁版的所有内容。预编译的简洁版包含以下文件：</p>
<pre>
zui/
└── dist/
    ├── css/                     CSS文件
    │   ├── zui.lite.css
    │   ├── zui.lite.min.css
    │   └── zui.lite.map.css
    ├── js/                      Javascript文件
    │   ├── zui.lite.js
    │   └── zui.lite.min.js
    └── fonts/                   图标字体文件
        ├── zenicon.eot
        ├── zenicon.ttf
        ├── zenicon.woff
        └── zenicon.svg
</pre>
        <h3>独立组件</h3>
        <p>一些组件可能既不包含在标准版中，也没有包含在简洁版中，使用时需要配合标准版或简洁版独立引用。可以在以下目录中找到独立组件包含的文件：</p>
<pre>
zui/
└── dist/
    └── lib/                      独立加载的组件
        ├── chosen/               Chosen组件
        ├── datetimepicker/       日期时间选择组件
        ├── datatable/            数据表格组件
        └── ...                   更多组件....
</pre>
        <h3>自定义版本</h3>
        <p>如果你需要更精确的控制预编译版本所包含的内容，强烈建议下载我们的源码来进行自定义配置并编译独一无二的版本。请参考章节<a href="#grunt">编译及定制</a>。</p>

        <h3>组件清单</h3>
        <p>组件清单帮助你快速查找所需的组件是否包含在指定版本中。</p>
        <table class="table table-bordered" id="buildTable">
          <thead>
            <th data-width="auto">组件</th>
            <th data-width="15%" style="width: 15%" class="text-center">标准版</th>
            <th data-width="15%" style="width: 15%" class="text-center">简洁版</th>
            <th data-width="15%" style="width: 15%" class="text-center">独立组件</th>
            <th data-width="30%" style="width: 30%" class="text-center">版本要求</th>
          </thead>
          <tbody>
            <tr><td colspan="5" class="text-muted">正在加载列表...</td></tr>
          </tbody>
        </table>
      </section>

      <section id="grunt">
        <div class="page-header">
          <h2>编译及定制</h2>
        </div>
        <p>ZUI使用 <a href="http://gruntjs.com/">Grunt</a> 作为编译系统。如果不了解 Grunt 也没有关系，Grunt是一个非常棒而且容易上手的工具。下面给出简要步骤来准备编译ZUI，如果想了解更多请访问Grunt官方网站。</p>
        <h3>安装Grunt</h3>
        <p>Grunt构建在nodejs之上。在安装Grunt之前需要首先<a href="http://nodejs.org/download/" target="_blank">下载并安装node.js</a>。最新版的nodejs已包含npm（<a href="http://npmjs.org/" target="_blank">node packaged modules</a>）。npm是nodejs用来管理扩展包的工具。</p>
        <p>安装nodejs之后，在命令行进行如下操作：</p>
        <ol>
          <li>在全局环境中安装<code>grunt-cli</code>：<code>npm install -g grunt-cli</code>。</li>
          <li>进入ZUI源码目录，执行<code>npm install</code>命令。nmp将读取包配置文件<code>package.json</code>文件并自动安装所有依赖的扩展包。</li>
        </ol>
        <p>完成上述步骤就可以进行编译了。只需要进入ZUI中使用命令行输入对应的命令就可以启动编译任务。内置的<code>build</code>命令可以完成大部分编译任务。以下为ZUI内置的一些常用任务命令。</p>
        <table class="table table-bordered">
          <thead>
            <th style="width: 200px">命令</th>
            <th style="width: 40%">说明</th>
            <th>输出目录</th>
          </thead>
          <tr>
            <td><code>grunt build:standard</code></td>
            <td>编译标准版</td>
            <td><ul>
              <li>dist/js/zui*.js</li>
              <li>dist/css/zui*.css</li>
              <li>dist/fonts/**</li>
            </ul></td>
          </tr>
          <tr>
            <td><code>grunt build:lite</code></td>
            <td>编译简洁版</td>
            <td>
              <ul>
                <li>dist/js/zui.lite*.js</li>
                <li>dist/css/zui.lite*.css</li>
                <li>dist/fonts/**</li>
              </ul>
            </td>
          </tr>
          <tr>
            <td><code>grunt build:dist</code></td>
            <td>编译标准版和简洁版以及常用独立组件</td>
            <td><ul>
              <li>dist/js/**</li>
              <li>dist/css/**</li>
              <li>dist/fonts/**</li>
              <li>dist/lib/*/**</li>
            </ul></td>
          </tr>
          <tr>
            <td><code>grunt dist</code></td>
            <td><code>grunt build:dist</code>的简单写法</td>
            <td><ul>
              <li>dist/js/**</li>
              <li>dist/css/**</li>
              <li>dist/fonts/**</li>
              <li>dist/lib/*/**</li>
            </ul></td>
          </tr>
          <tr>
            <td><code>grunt build:doc</code></td>
            <td>编译文档所需资源</td>
            <td><ul>
              <li>doc/js/zui*.js</li>
              <li>doc/css/zui*.css</li>
              <li>doc/fonts/**</li>
            </ul></td>
          </tr>
          <tr>
            <td><code>grunt build:theme</code></td>
            <td>编译主题</td>
            <td>
              <ul>
                <li>dist/css/zui-theme*.css</li>
              </ul>
            </td>
          </tr>
          <tr>
            <td><code>grunt build:[build name]</code></td>
            <td>编译独立组件包，<code>[build name]</code>为组件包名称，可以为<code>calendar</code>、<code>kindeditor</code>、<code>chosen</code>等</td>
            <td>
              <ul>
                <li>dist/lib/[build name]/**</li>
              </ul>
            </td>
          </tr>
          <tr>
            <td><code>grunt build:[control name]</code></td>
            <td>编译单独控件，<code>[control name]</code>为控件名称，可以为<code>button</code>、<code>alerts</code>、<code>panels</code>等</td>
            <td>
              <ul>
                <li>dist/lib/[control name]/**</li>
              </ul>
            </td>
          </tr>
        </table>
        <p>如果了解Grunt，当然可以通过编辑<code>Gruntfile.js</code>文件来定义自己的编译任务。</p>
      </section>

      <section id="browsers">
        <div class="page-header">
          <h2>受支持的平台</h2>
        </div>
        <h3>桌面浏览器</h3>
        <ul>
          <li>IE8+</li>
          <li>Opera 12+</li>
          <li>Firefox 4+</li>
          <li>Safari 5+</li>
          <li>Chrome 10+</li>
        </ul>

        <h3>移动浏览器</h3>
        <ul>
          <li>IOS 4+ Safari</li>
          <li>Chrome for Android</li>
          <li>Chrome for IOS</li>
          <li>Chrome for Android</li>
          <li>Windows Phone 7+ IE</li>
        </ul>
        <p>最新的浏览器都能获得最佳体验，在旧的浏览器上ZUI中的部分特性（例如圆角或阴影效果）无法使用。</p>
      </section>
    </div>

    <script src="../assets/jquery.js"></script>
    <script src="../dist/js/zui.min.js"></script>
    <script src="../assets/google-code-prettify/prettify.js"></script>
    <script src="js/doc.js"></script>

  <script src="http://s95.cnzz.com/stat.php?id=1253026255&web_id=1253026255"></script>
<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-53781622-1', 'auto');
  ga('send', 'pageview');
</script>
  </body>
</html>
